Using object specifiers in place of other parameters / 4
Apple events defined in the Mail suite / 5
Send —Send a Document / 6
Object classes defined in the Mail suite / 7
cMailer—a Mailer / 9
cMailAddress—a representation of an address/ 13
cRecipient—an entry in the Mailer's address list/ 16
cSender—the entry in the Mailer's from field / 18
Descriptor Types defined in the Mail suite / 20
typeMailAddress—a mailer / 20
typePackedDSSpec—a mailer / 22
Key forms defined in the Mail suite / 23
Comparison operators defined in the Mail suite / 24
Constants defined in the Mail suite / 25
Figures and Tables
Table 1 Apple events defined in the Mail suite / 7
Table 2 Apple event object classes defined in the Mail suite / 7
Figure 1 Object inheritance hierarchy for the Mail suite / 8
Table 3 Descriptor types defined in the Mail suite / 20
Table 4 Key forms defined in the Mail suite / 23
Table 5 Comparison operators defined in the Mail suite / 24
Table 6 Constants defined in the Mail suite / 25-26
The Mail Suite
The Mail suite defines Apple event constructs that are used for communicating with mail-capable server applications.
Introduction to the Mail suite
The Mail suite defines Apple event constructs that are elements of the Macintosh Mail Architecture and, when used in conjunction with the Apple Event Registry: Standard Suites, provide an interface for communicating with mail-capable applications in order to mail documents. For an application to use these events and objects, it must also support the Apple event constructs from the Core suite as defined in the Apple Event Registry: Standard Suites.
Overview of the Mail suite
The object model for the Mail Suite is based on the AOCE Mailer. To use the Mail suite, you may wish to familiarize yourself the Standard Mail Package and its Mailer functionality.
The Standard Mail Package
With the addition of AOCE technology to the Macintosh environment, the basic functionality of a document-oriented appliction on the Macintosh has been extended from supporting merely "saving" and printing" documents to "sending" documents. The AOCE Standard Mail Package provides the support for every Macintosh application to integrate Mail functionality and services into the user’s experience.
Mailer Concepts
A Mailer is a "mailing label" that can be affixed to a document in order to mail it. The mailer contains from, to, cc, bcc and subject information and optionally a list of enclosures. The mailer remains attached to the document after sending so that the addressing information, enclosures and other information such as sending date and time are available to the recipent.
A document may contain multiple mailers if it is forwarded. For example, Amy, the original author of a document, attaches a mailer and sends the document to Bob. The document Bob receives contains the mailer that Amy created but it is marked as "received". Bob can then forward the document by adding a second mailer "on top" of the first and address this to Catherine and enclose a document. The document Catherine receives will then have two mailers. The top-most mailer (the one with the highest ordinal value) is the most recent and is either the mailer used to send to this recipient or is being prepared to be mailed to a new distribution list.
Scope of the Mailer Concept and Mail Suite
The mailer represents the most complete and robust model upon which an object model for the Mail suite can be based. However, it does not require that the application support the Mailer human interface where it is inappropriate to do so. The Mailer is simply the model used to represent the addressing and other information required by the Mail suite. The Mail suite is applicable to every application that supports mailing documents.
For more information about the Standard Mail Package and Mailer concepts, please consult the "Standard Mail Package" Chapter of Inside Macintosh.
Typical uses of the Mail suite
The following scenarios illustrate the types of Mail-capable applications that are likely to be servers for the Mail suite and the types of applications that are likely toe clients:
n Word processing applications can be used for mail merge in conjunction with an external scripting language.
n Workflow servers will use the suite to keep forms and other documents moving through a workflow system.
n Database and accounting applications that keep track of customer, vendor and other records containing phone numbers. These applications can both place telephone calls and present information whenever there is an incoming call.
n Agents that acquire information on behalf of a user can mail back desired information via a mail capable application, such as a spreadsheet or charting program.
Using object specifiers in place of other parameters
In all of the suites except the Finder suite, you can substitute an object specifier for any parameter of an Apple event that is not already defined to be an object specifier. This object specifier must specify a single object. When you substitute an object specifier for a parameter, the actual value of the parameter is the value of the default descriptor record for the specified object (that is, the value you get when you send a Get Data Apple event for the object and do not specify a particular descriptor type for the result.)
Apple events defined in the Mail suite
The Apple events defined in the Mail suite are described in the following sections. Table 1 lists these Apple events.
n Table 1 Apple events defined in the Mail suite
Name Requested action
SendLetter Send a document
SendLetter—send a document
The SendLetter Apple event mails a document.
Event Class kAEMailEvents
Event ID kAESendLetter
Parameters
keyDirectObject
Description: The document to send
Descriptor Type: typeObjectSpecifier
Required or Optional? Required
keyAEIncludeSnapShotFmt
Description: The document to send
Descriptor Type: typeBoolean
Required or Optional? Optional
keyAEIncludeStandardFmt
Description: The document to send
Descriptor Type: typeBoolean
Required or Optional? Optional
keyAEIncludeMainEnclFmt
Description: The document to send
Descriptor Type: typeOSType
Required or Optional? Optional
keyAEMailPriority
Description: The priority of a received letter. The value of this paarmeter will be enumHighPriority, enumNormalPriority or enumHLowPriority. The default is enumNormalPriority .
Descriptor Type: typeEnumeration
Required or Optional? Optional
Reply Parameters None
Object classes defined in the Mail suite
The Apple event object classes defined in the Mail suite are described in the following sections. Table 2 lists these object classes.
n Table 2 Apple event object classes defined in the Mail suite
Object class ID Description
cMailer A representation of a mailer in a document
Figure 2 illustrates the inheritance hierarchy for the object classes defined in the Mail suite. Listed for each object class are the properties, element classes, and Apple events that have not been inherited from object classes higher in the inheritance hierarchy.
n Figure 1 Object inheritance hierarchy for the Mail suite
cMailer—a Mailer
The cMailer object class is the class for representation of a Mailer or "mailing label" in a document. A Mailer must be added to a document and a subject and recipient must be specified before the document can be mailed (the From field should be defaulted by the server). The other properties and elements of the Mailer are optional.
Every cMailer is owned by a Document and appears as an element in exactly one Document. One document may have zero or more cMailers.
The top-most mailer may or may not be a "draft mailer" which means that it has not yet been sent. The pReceived property indicates whether this letter has been received or is being prepared for sending. If a given cMailer is draft mailer, then the following apply:
n pReceived is FALSE.
n pMailAddress in pFrom is undefined.
n pASendDateTime is undefined.
n pHasContent is undefined.
n pFrom, pSubject, cRecipient and cFile are modifiable.
If a given cMailer is a received mailer, then the following apply:
n pReceived is TRUE.
n pIdentity in pFrom is undefined.
n no properties or elements of the cMailer are modifiable.
Superclass cObject (Core suite)
Default Descriptor
Type
typeObjectSpecifier
Properties
pBestType
Description: The descriptor type that can contain the most information from objects of this object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pClass
Description: The four-character class ID for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pDefaultType
Description: The default descriptor type for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pFrom
Description: The sender of this mailer. The pIdentity contained within the sender is only valid if the given Mailer is a draft Mailer. This is only modifiable when the Mailer is a draft Mailer.
Object Class ID: cSender
Inherited? No
Modifiable or
Non-modifiable? Modifiable
pSubject
Description: The subject of a received letter. This is only modifiable when the Mailer is a draft Mailer.
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Modifiable
pSendDateTime
Description: The sending date and time of the letter. This is only defined when the given Mailer has been received.
Object Class ID: cDateTime
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pReceived
Description: This flag indicates whether or not the given mailer has been received or is a draft mailer being prepared for sending.
Object Class ID: cBoolean
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pHasContent
Description: This flag indicates whther or not there is new letter content associated with a given mailer.
Object Class ID: cBoolean
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
Element Classes
cRecipient
Description: A Recipient to whom this letter is addressed.
The cMailAddress object class is the class for the representation of a destination for a letter. In addition to the information necessary for the appropriate mail transport to deliver the letter, cMailAddress includes the name, and if appropriate, the type of destination being mailed to. Note that the cMailAddress here is identical to the one found in the collaborative information suite except that no pName is supported i the Mail suite.
Superclass cObject
Default Descriptor
Type
typeIntlText
Properties
pBestType
Description: The descriptor type that can contain the most information from objects of this object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pClass
Description: The four-character class ID for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pDefaultType
Description: The default descriptor type for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pAddresseeName
Description: The name of the addressee
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pAddresseeType
Description: The type of the addressee. For Mail, this is normally 'User'.
Object Class ID: cType
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pAddressType
Description: The type of the address
Object Class ID: cType
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pAddress
Description: The actual address of the type specified by pAddressType in the address space specified by pAddressSpace.
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pDirectory
Description: The name of the address space or the subaddress space specified as a path within the address space for direct addressing or the directory or directory node path for indirect addressing.
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pDirectoryType
Description: The type of the address space or directory.
Object Class ID: cType
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pDirectoryID
Description: The unique ID of the address space or directory.
Object Class ID: cLongInteger
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
Element Classes None
Apple Events
Apple events from the Core suite:
Clone Inherited from cObject
Count Elements Inherited from cObject
Create Element Inherited from cObject
Delete Inherited from cObject
Do Objects Exist Inherited from cObject
Get Class Info Inherited from cObject
Get Data Inherited from cObject
Get Data Size Inherited from cObject
Move Inherited from cObject
Set Data Inherited from cObject
cRecipient—an entry in a Mailer address list
The cRecipient object class is used to represent one destination specified in a mailer. In addition to specifying the mail address for the recipient, it specifies whether the recipient is a primary recipient (To:), copied recipent (CC:) or blind-copied recipient (BCC:).
Superclass cObject (Core suite)
Default Descriptor
Type
typeObjectSpecifier
Properties
pBestType
Description: The descriptor type that can contain the most information from objects of this object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pClass
Description: The four-character class ID for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pDefaultType
Description: The default descriptor type for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pMailAddress
Description: The mail address for the recipient.
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Modifiable
pRecipientType
Description: Specifies To:, CC:, or BCC:. The value of this property will be kAEToRecipient, kAECCRecipient and kAEBCCRecipient respectively.
Object Class ID: cEnumeration
Inherited? No
Modifiable or
Non-modifiable? Modifiable
Element Classes None
Apple Events
Apple events from the Core suite:
Clone Inherited from cObject
Count Elements Inherited from cObject
Create Element Inherited from cObject
Delete Inherited from cObject
Do Objects Exist Inherited from cObject
Get Class Info Inherited from cObject
Get Data Inherited from cObject
Get Data Size Inherited from cObject
Move Inherited from cObject
Set Data Inherited from cObject
cSender—the entry in the Mailer's From field
The cSender object class is the class for representation of the sender of a letter. The pIdentity property of this object is only valid (and modifiable) in a draft mailer. It is undefined in a recieved letter. Likewise, the pMailAddress property is invalid for a draft letter but valid for a received letter.
Superclass cObject (Core suite)
Default Descriptor
Type
typeObjectSpecifier
Properties
pBestType
Description: The descriptor type that can contain the most information from objects of this object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pClass
Description: The four-character class ID for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pDefaultType
Description: The default descriptor type for the object class
Object Class ID: cType
Inherited? Yes, from cObject
Modifiable or
Non-modifiable? Non-modifiable
pIdentity
Description: The AOCE identity of the sender. This is only valid if the identity has already been explicitly set and will not be valid for a recieved letter.
Object Class ID: cLongInteger
Inherited? No
Modifiable or
Non-modifiable? Modifiable
pMailAddress
Description: The mail address of the sender. This is only valid when the letter is received.
Object Class ID: cMailAddress
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
pName
Description: The name of the sender.
Object Class ID: cIntlText
Inherited? No
Modifiable or
Non-modifiable? Non-modifiable
Element Classes None
Apple Events
Apple events from the Core suite
Count Elements Inherited from cObject
Do Objects Exist Inherited from cObject
Get Class Info Inherited from cObject
Get Data Inherited from cObject
Get Data Size Inherited from cObject
Set Data Inherited from cObject
Descriptor types defined in the Mail suite
The new descriptor types defined in the Mail suite are described in the following section.
n Table 3 Descriptor types defined in the Mail suite
Descriptor type Description
typeMailAddress a mail address descriptor
typePackedDSSpec an AOCE PackedDSSpec data structure
typeMailAddress—a mail address descriptor
A typeMailAddress descriptor record contains the data for a cMailAddress object. It includes all the information necessary to recreate the original cMailAddress object.
Description To create a typeMailAddress descriptor record, you coerce an AE record containing the following fields into the equivalent typeMailAddress descriptor record:
Keyword Descriptor type Description
keyAEDirectory typeIntlText the address space
keyAEDirectoryType typeIntlText the address space type
keyAEDirectoryID typeIntlText the address space discriminator
keyAEAddressType typeIntlText the address type
keyAEAddress typeIntlText the actual address in the specified address space
keyAEAdresseeName typeIntlText the addressee name
keyAEAddresseeType typeIntlText the addressee type
All Mail Apple event servers must support coercion of typeMailAddress into typeIntlText and the reverse. When mapping the data into IntlText the format described below is to be used.
The following characters are used as tokens:
".", "<", ">", "@" and "\"
The latter is the escape character for quoting the other tokens in fields where they are reserved as indicated below.
The component fields of the string address are listed below. Every field except the Addressee Name and the Directory Name field can be optional depending on the circumstances.
NAM = Addressee Name (".", "<" and "@" must be quoted with "\")
TYP = Addressee Type ('User' if not specified, "<" must be quoted with "\")
EXT = Address Type (Default = 'entn')
EXV = Address Value (">" must be quoted with "\")
DIR = Directory or Address Space Name ("." and "<" must be quoted with "\")
This may be expressed as a Path{Subspace of Address Space}
so it would be (NODENAME.)*DIR where "(_)*" means "zero or more of _"
DIT = Directory or Address Space Type ('adap' used if ambiguous & unspecified)
DID = Directory or Address Space Discriminator (Required if DIT is specified)
The TYP, EXT, and DIT fields are all four bytes which may be any displayable ASCII characters.
The string representation for addresses is then as follows:
NAM.TYP<EXT.EXV>@DIR<DIT.DID>
Examples:
Michael Bayer@Evangelism.MSAD.APPLE
M\. Bayer@Evangelism.MSAD.APPLE
Michael Bayer.User@Evangelism.MSAD.APPLE
Evangelists.Group@Evangelism.MSAD.APPLE
NASDAQ.StockAgent@CORP.APPLE
Michael Bayer<entn.123.456>@Evangelism.MSAD.APPLE<adap,001>
Michael Bayer<alan.MBQuadra.Evangelism>@AppleR&DNetwork
Michael Bayer<fax .+1(408)974-1211>@FAX
Michael Bayer<smtp.bayer1@applelink.apple.com>@INTERNET<smtp,0>
Michael Bayer<alnk.BAYER1>@AppleLink
NOTE: These string representations of an address are always represented using an appropriate script code. The tokens listed above (".", "<", ">", "@" and "\") are represented in the script specified by the IntlText. The Addressee Type, Extension Type and the Directory Type are each 4 Bytes and are always interpreted using Roman ASCII.
typePackedDSSpec—a mail address descriptor
A typePackedDSSpec descriptor record contains the data for a cMailAddress object represented as an AOCE PackedDSSpec data structure as defined in the AOCE Utilities chapter of Inside Macintosh. It includes all the information necessary to recreate the original cMailAddress object.
All Mail Apple event servers must support coercion of typePackedDSSpec into typeIntlText and typeMailAddress and the reverse. When mapping the data into typeIntlText the same format described for coercion of typeMailAddress is to be used.
Key forms defined in the Mail suite
Table 4 lists the key forms defined in the Mail suite. The italicized words in each example correspond to the key (the portion of the object specifier record that distinguishes an object from other objects of the same class in the same container). For more information about keys and key forms, see the Apple Event Manager chapter of Inside Macintosh: InterApplication Communication.
n Table 4 Key forms defined in the Mail suite
Key form constant Description
formAbsolutePosition Specifies the position of an element in relation to the beginning or end of its container (for example, “word 5 of . . . ”), or specifies one or more elements with a constant defined in the Apple Event Manager chapter of Inside Macintosh: InterApplication Communication, such as kAEFirst (for example, “the first word in paragraph 12 . . . ”) or kAEAll (for example, “all the words in paragraph 12 . . . ”)
formName Specifies an element by its name (for example, “the document named ‘MyDoc’ ”)
formPropertyID Specifies a property of an object by its four-character property ID (for example, “the font of word 1”)
formRange Specifies a list of elements between two other elements (for example, “the words between ‘Wild’ and ‘Zanzibar,’ inclusive”)
formRelativePosition Specifies an element immediately before or after a container (for example, “the next word after the word whose style is bold”)
formTest Specifies one or more elements that pass a test; values of one or more properties or elements can be tested (for example, “the first paragraph that is centered and that begins with the word ‘Wild’ ”)
Comparison operators defined in the Mail suite
Table 5 lists the comparison operators defined in the Mail suite.
n Table 5 Comparison operators defined in the Mail suite
Comparison operator constant Operator Description
kAEBeginsWith 'bgwt' The value of the first operand begins with the value of the second operand (for example, the string “outside line” begins with the string “out”)
kAEContains 'cont' The value of the first operand contains the value of the second operand (for example, the string “outside line” contains the string “side”)
kAEEndsWith 'ends' The value of the first operand ends with the value of the second operand (for example, the string “outside line” ends with the string “line”)
kAEEquals '= ' The value of the first operand is equal to the value of the second operand
kAEGreaterThan '> ' The value of the first operand is greater than the value of the second operand
kAEGreaterThanEquals '>= ' The value of the first operand is greater than or equal to the value of the second operand
kAELessThan '< ' The value of the first operand is less than the value of the second operand
kAELessThanEquals '<= ' The value of the first operand is less than or equal to the value of the second operand
Constants defined in the Mail suite
Table 6 lists the constants defined in the Mail suite.
n Table 6 Constants defined in the Mail suite
Constant Value
cMailAddress 'mAdd'
cMailer 'mhdr'
cRecipient 'mrcc'
cSender 'msnd'
enumPriorityHigh 'high'
enumPriorityLow 'low'
enumPriorityNormal 'medi'
kAEMailEvents 'MAIL'
kAESendLetter 'send'
kAEToRecipient ' to '
kAECCRecipient ' cc '
kAEBCCRecipient 'bcc '
keyAEAddresseeName 'pAdN'
keyAEAddresseeType 'pRTy'
keyAEAddressType 'pATy'
keyAEAddress 'pAdd'
keyAEDirectory 'pDir'
keyAEDirectoryID 'pDID'
keyAEDirectoryType 'pDTy'
keyAEIncludeAppleMailFmt 'lamf'
keyAEIncludeMainEnclFmt 'lmef'
keyAEIncludeSnapShotFmt 'lssf'
keyAEPriority 'PRTY'
pAddresseeName 'pAdN'
pAddresseeType 'pRTy'
pAddressType 'pATy'
pAddress 'pAdd'
pDirectory 'pDir'
pDirectoryID 'pDID'
pDirectoryType 'pDTy'
n Table 6 Constants defined in the Mail suite (Continued)